home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / basic / qbeditr.com / EDITOR.DOC < prev    next >
Encoding:
Text File  |  1989-02-27  |  10.7 KB  |  241 lines
  1. THE OBJECT MODULE, INCLUDE FILE AND DOCUMENTATION IN THIS ARCHIVE ARE EXPRESSLY
  2. NOT BEING PLACED IN THE PUBLIC DOMAIN.  You may utilize the object module in 
  3. modified or unmodified form in your own programs without restriction.  You may 
  4. distribute unmodified copies of the original archive which includes the files: 
  5.  
  6.               Editor.obj
  7.               Editor.doc (this file)
  8.               Editor.bi
  9.  
  10. (c) 1989 Christopher P. Rouse
  11.  
  12.                                     OVERVIEW
  13.  
  14. Editor uses essentially the same key combinations as the QuickBASIC program
  15. editor.  The only real difference is that, since Editor is designed to be used
  16. with single line entry fields in a data base environment, it does not support
  17. the vertical cursor movement functions such as the up and down arrows, page up 
  18. or down, etc.  The following table lists the editing keys that are supported: 
  19.  
  20.                  Key                      Action
  21.  
  22.               Left Arrow       Move the cursor one character left
  23.               Right Arrow      Move the cursor one character right
  24.               Ctrl-Left Arrow  Move the cursor one word left
  25.               Ctrl-Right Arrow Move the cursor one word right
  26.  
  27.               Ctrl-A           Move the cursor one word left
  28.               Ctrl-S           Move the cursor one character left
  29.               Ctrl-D           Move the cursor one character right
  30.               Ctrl-F           Move the cursor one word right
  31.  
  32.               Ctrl-H           Delete the character to the left
  33.               Backspace        Delete the character to the left
  34.               Ctrl-T           Delete the word at the cursor
  35.               Ctrl-Y           Delete the entire line
  36.  
  37.               Ins              Toggle insert mode
  38.  
  39. Editor makes no distinction between the dedicated cursor movement keys available
  40. on the enhanced keyboards and the traditional keys on the numeric keypad.
  41.  
  42. Editor uses the keyboard status byte at 0040:0017h to track the insert status.
  43. Setting bit 7 will cause the insert state to be active.  This is consistent
  44. with DOS and BIOS.  At this time, no change is made in cursor size to indicate
  45. the current status.
  46.  
  47. Editor writes directly to the display adapter and is NOT synchronized with the
  48. vertical retrace.  This will cause "snow" with some CGA adapters.  While
  49. noticable, the duration of the snow is so brief that I didn't feel the benefit
  50. of eliminating the snow outweighed the increase in program size that would be
  51. required to determine display adapter type and synchronize the display write.
  52. If you encounter a situation that causes unacceptable "snowing", please let me
  53. know. (Include system processor, adapter type and brand, and size of the field
  54. that Editor was editing.)
  55.  
  56. Editor is designed for use with text modes only.  It has been tested with 40
  57. and 80 column screen modes.  It should work with other screen widths (up to 255
  58. columns) but this has not been verified.  Using Editor in graphics modes will
  59. cause unpredictable results (a euphamism for "it definitely won't work and
  60. might hang the system").
  61.  
  62. Editor uses BIOS calls to accept input from the keyboard, therefore redirection 
  63. of STDIN will not function.
  64.  
  65. Editor supports "windowed" editing.  A field to be edited may be longer than
  66. what is displayed.  Editor will scroll the field horizontally to accomodate the
  67. additional length.
  68.  
  69. While not really designed for it, there is nothing in Editor that precludes 
  70. its' use on multi-line fields.  Long edit fields will aggravate "snow" problems 
  71. on some CGA adapter/monitor combinations. 
  72.  
  73.                              USAGE WITH QuickBASIC
  74.  
  75. Function and Subroutine Declaratons:
  76.  
  77. DECLARE FUNCTION EditString% (Text$, BYVAL Row%, BYVAL Column%, BYVAL Colour%)
  78. DECLARE FUNCTION EditWindow% (BYVAL WindowLen%, Text$, BYVAL Row%, BYVAL Column%, BYVAL Colour%)
  79. DECLARE SUB EdRetCodes (BYVAL ArraySeg%, BYVAL ArrayOffs%, BYVAL SizeOfArray%)
  80. DECLARE SUB PushKey (BYVAL Key2Push%)
  81.  
  82. EditString and EditWindow:
  83.  
  84.               Text$ is the "default" or pre-existing text string to be edited
  85.               Row% is the display row that the text is to be edited on
  86.               Column% is the column postion of the text string
  87.               Colour% is the color to use on the display (see "Attributes")
  88.               WindowLen% is the length of the display window
  89.  
  90. EditString and EditWindow are functionally identical except that EditWindow 
  91. limits the number of characters that are displayed and performs horizontal 
  92. scrolling.  Throughout this documentation the term Editor will refer to both 
  93. EditString and EditWindow.
  94.  
  95. In order to display the cursor, a LOCATE , , 1 must have been executed prior to 
  96. calling Editor.  When Editor is called, it first displays Text$ at Row%, 
  97. Column% using the color specified by Colour%.  Then the user may modify Text$ 
  98. using the editing keys previously mentioned.  Editor locates the QB cursor at 
  99. Row%, Column% prior to returning.  This facilitates highlighting the active 
  100. field:
  101.  
  102.               DECLARE FUNCTION EditField%(Text$, BYVAL Row%, BYVAL Column%, Colour%)
  103.               COLOR 7, 0
  104.               CLS
  105.               Text$ = "Hello, World"
  106.               ReturnKey% = EditField(Text$, 10, 35, &H70)
  107.               PRINT Text$
  108.  
  109. will display "Hello, World" in reverse video, allow the user to change the 
  110. contents of Text$, and then display Text$ in normal video.  Editor ALWAYS 
  111. returns when Enter, Tab, Shift-Tab or Esc is pressed.  Editor returns the ASCII 
  112. value and scan code of the key that caused the return:
  113.  
  114.                Key       Value Returned
  115.  
  116.               Enter          &H1C0D
  117.               Tab            &HF09
  118.               Shift-Tab      &HF00
  119.               Esc            &H11B
  120.  
  121. ANDing the returned value with &HFF will isolate the ASCII portion, dividing 
  122. it by &H100 will isolate the keyboard scan code.
  123.  
  124.  
  125. EdRetCodes:
  126.  
  127. DECLARE SUB EdRetCodes (BYVAL ArraySeg%, BYVAL ArrayOffs%, BYVAL SizeOfArray%)
  128.  
  129.               ArraySeg% is the value returned by VARSEG(Array%(?))
  130.               ArrayOffs% is the value returned by VARPTR(Array%(?))
  131.               SizeOfArray% is the number of elements in Array%
  132.  
  133. EdRetCodes allows you to define other Scan Code - ASCII Code combinations which 
  134. will cause Editor to return.  An arbitrary limit of 100 additional return codes 
  135. has been placed on Editor.  Passing a value of SizeOfArray% greater than 100 
  136. will cause unpredictable results (probably hang the system) during subsequent 
  137. calls to Editor.  The values of the elements of the array should be valid 
  138. values returned by BIOS call 16h, function 0.  Invalid values are ignored.  
  139. Editor checks to see if a keypress should return before it checks to see if it 
  140. is a "special" key, therefore you may make any of the "special" keys (Ctrl-Y, 
  141. for instance) generate a return instead of taking the normal action (clear the 
  142. line). 
  143.  
  144. Editor ignores the status of the Caps Lock, Num Lock and Shift keys when 
  145. determining whether or not to return.  This means that Alt-F and Alt-f are 
  146. identical to Editor.  Editor does not require you to define the same key many 
  147. times in the way that user defined keys in QB do.  This allows you to "poll" 
  148. the keyboard input in lieu of event trapping.  This can significantly decrease 
  149. program size and increase execution speed in addition to eliminating some of 
  150. the potential problems caused by event trapping in multi-module programs and 
  151. libraries.  
  152.  
  153. Passing a value of 0 for SizeOfArray% will cancel assignments made by a prior 
  154. call to EdRetCodes.  
  155.  
  156.  
  157. PushKey:
  158.  
  159. DECLARE SUB PushKey (BYVAL Key2Push%)
  160.  
  161. PushKey was written to provide a way for a trapped event to force a return from 
  162. Editor.  Key2Push% uses the same Scan Code - ASCII Code values that Editor 
  163. returns.  It could also be used to provide a small macro capability to a 
  164. program.  PushKey may be called up to 15 times before a key must be read using 
  165. INKEY$, INPUT$, INPUT or LINE INPUT.  The 16th call to PushKey effectively 
  166. cancels the first 15.
  167.  
  168. WARNING: PushKey has only been tested on a limited basis.  It has never hung a 
  169. system but does not function correctly in conjunction with a SLEEP statement.
  170.  
  171.  
  172. Attributes:
  173.  
  174. Editor uses color attributes in the same way they are used in assembler.  The 
  175. upper "nibble" of the attribute byte defines the background color, the lower 
  176. nibble defines the foreground color.  It may be calculated from the BASIC way 
  177. of defining screen colors by:
  178.  
  179.               AsmColor = BasBG * &H10 + BasFG
  180.  
  181.       where
  182.  
  183.               AsmColor is the value to be passed to Editor.
  184.               BasBG is the background color
  185.               BasFG is the foreground color
  186.  
  187.  
  188. Memory Requirements and Distribution:
  189.  
  190. The Editor module will use approximately 1600 bytes of memory.  It requires 
  191. roughly 220 bytes of static data space (200 bytes of which is for defining 
  192. "return" keys).  All of this static data space has been placed in Edit_Text 
  193. segment (code) to preserve as much as possible of the rapidly shrinking DGROUP. 
  194.  
  195.  
  196. Comments, suggestions and constructive criticism are always appreciated.
  197.  
  198. Christopher P. Rouse
  199. 4684 N. 86 St.
  200. Milwaukee, WI  53225
  201.  
  202. (414) 535-1981
  203. CIS 71420, 614
  204.  
  205.  
  206.  
  207.          ----------------end-of-author's-documentation---------------
  208.  
  209.                         Software Library Information:
  210.  
  211.                    This disk copy provided as a service of
  212.  
  213.                         The Public (Software) Library
  214.  
  215.          We are not the authors of this program, nor are we associated
  216.          with the author in any way other than as a distributor of the
  217.          program in accordance with the author's terms of distribution.
  218.  
  219.          Please direct shareware payments and specific questions about
  220.          this program to the author of the program, whose name appears
  221.          elsewhere in  this documentation. If you have trouble getting
  222.          in touch with the author,  we will do whatever we can to help
  223.          you with your questions. All programs have been tested and do
  224.          run.  To report problems,  please use the form that is in the
  225.          file PROBLEM.DOC on many of our disks or in other written for-
  226.          mat with screen printouts, if possible.  The P(s)L cannot de-
  227.          bug programs over the telephone.
  228.  
  229.          Disks in the P(s)L are updated monthly, so if you did not get
  230.          this disk  directly from the P(s)L,  you should be aware that
  231.          the files in this set may no  longer be the current versions.
  232.  
  233.          For a copy of the latest monthly software library newsletter
  234.          and a list of the 1,800+ disks in the library, call or write
  235.  
  236.                         The Public (Software) Library
  237.                               P.O.Box 35705 - F
  238.                            Houston, TX 77235-5705
  239.                                (713) 665-7017
  240.  
  241.